﻿<?xml version="1.0" encoding="utf-8"?>
<?xml-stylesheet type="text/xsl" href="style.xsl"?>
<asdf name="CLUnit" author="Tapiwa Gutu"  version="0.2.3">
  <description>
    <p>
      <b>CLUnit</b> is a Common Lisp unit testing framework. It is designed to be easy to use so that you can quickly start testing.
    </p>
    <p>
      CLUnit provides a rich set of features aimed at improving your unit testing experience:
      <ul>
        <li>Multiple inheritance for test suites allows you to group tests into hierarchies.</li>
        <li>Composes the test results of each test run into a single report.</li>
        <li>Allows redefinition of inline functions and macros without having to redefine your tests.</li>
        <li>Supports composable test suite fixtures.</li>
        <li>Allows for an interactive testing process which gives you access to the test environment.</li>
        <li>Provides visual feeback of the unit test progress.</li>
        <li>Extensible test reporting. Builtin support for default reporting and TAP output.</li>
      </ul>
    </p>
  </description>

  <symbols>
    <symbol name="*clunit-report-format*" type="Special">
      <return-type>(or :default :tap nil)</return-type>
      <description>
        <p>Controls the output format of the unit test results.
        Possible values are :default, :tap or NIL.</p>
      </description>
    </symbol>

    <symbol name="*clunit-equality-test*" type="Special">
      <description>
        <p>
          Holds the equality test used to compare values by the ASSERT-EQUALITY macro.<br/>
          The default value <em>#'equalp</em> is reset at the end of each test/suite run.
        </p>
      </description>
    </symbol>

    <!-- Assertion Macros -->
    <symbol name="assert-true" type="Macro">
      <argument  value-type="t" arg-type="required" name="expression"/>
      <argument  value-type="LIST" arg-type="body" name="forms"/>
      <description>
        <p>
          Evaluates EXPRESSION as an assertion, an assertion passes if it returns any non-NIL value.
          FORMS and their values are printed if the test fails.
          Remember in Common Lisp any non-NIL value is true, if you want a strict binary assertion test use <b>(assert-eq t expression)</b> instead.
        </p>
      </description>
    </symbol>

    <symbol name="assert-false" type="Macro">
      <argument  value-type="t" arg-type="required" name="expression"/>
      <argument  value-type="LIST" arg-type="body" name="forms"/>
      <description>
        <p>
          Evaluates EXPRESSION as an assertion, an assertion passes if it returns NIL.
          FORMS and their values are printed if the test fails.<br/>
          <code>(assert-false (= 1 2)) ; This assertion passes.</code>
        </p>
      </description>
    </symbol>

    <symbol name="assert-eq" type="Macro">
      <argument  value-type="t" arg-type="required" name="value"/>
      <argument  value-type="t" arg-type="required" name="expression"/>
      <argument  value-type="LIST" arg-type="body" name="forms"/>
      <description>
        <p>
          Evaluates EXPRESSION as an assertion, an assertion passes if (EQ VALUE EXPRESSION) returns true.
          FORMS and their values are printed if the test fails.
        </p>
      </description>
    </symbol>

    <symbol name="assert-eql" type="Macro">
      <argument  value-type="t" arg-type="required" name="value"/>
      <argument  value-type="t" arg-type="required" name="expression"/>
      <argument  value-type="LIST" arg-type="body" name="forms"/>
      <description>
        <p>
          Evaluates EXPRESSION as an assertion, an assertion passes if (EQL VALUE EXPRESSION) returns true.
          FORMS and their values are printed if the test fails.
        </p>
      </description>
    </symbol>

    <symbol name="assert-equal" type="Macro">
      <argument  value-type="t" arg-type="required" name="value"/>
      <argument  value-type="t" arg-type="required" name="expression"/>
      <argument  value-type="LIST" arg-type="body" name="forms"/>
      <description>
        <p>
          Evaluates EXPRESSION as an assertion, an assertion passes if (EQUAL VALUE EXPRESSION) returns true.
          FORMS and their values are printed if the test fails.<br/>
          <code>
            (let ((q (+ 2 -2)))<br/>
            &#160;&#160;&#160;(assert-equal 4 q q))<br/>
            ;; This assertion fails and prints the message below with *clunit-report-format* set to :DEFAULT.
            <div style="background-color:black; color:green;">
              &#160;<br/>
              Expression: (EQUAL 4 Q)<br/>
              Expected: 4<br/>
              Returned: 0<br/>
              Q => 0<br/>
              &#160;<br/>
            </div>
          </code>
        </p>
      </description>
    </symbol>

    <symbol name="assert-equalp" type="Macro">
      <argument  value-type="t" arg-type="required" name="value"/>
      <argument  value-type="t" arg-type="required" name="expression"/>
      <argument  value-type="LIST" arg-type="body" name="forms"/>
      <description>
        <p>
          Evaluates EXPRESSION as an assertion, an assertion passes if (EQUALP VALUE EXPRESSION) returns true.
          FORMS and their values are printed if the test fails.
        </p>
      </description>
    </symbol>

    <symbol name="assert-equality" type="Macro">
      <argument  value-type="FUNCTION" arg-type="required" name="test"/>
      <argument  value-type="t" arg-type="required" name="value"/>
      <argument  value-type="t" arg-type="required" name="expression"/>
      <argument  value-type="LIST" arg-type="body" name="forms"/>
      <description>
        <p>
          Evaluates EXPRESSION as an assertion, an assertion passes if (FUNCALL TEST VALUE EXPRESSION) returns true.
          FORMS and their values are printed if the test fails.<br/>
          <code>(assert-equality #'string= "some string" "another string") ; This assertion fails.</code>
        </p>
      </description>
    </symbol>

    <symbol name="assert-equality*" type="Macro">
      <argument  value-type="t" arg-type="required" name="value"/>
      <argument  value-type="t" arg-type="required" name="expression"/>
      <argument  value-type="LIST" arg-type="body" name="forms"/>
      <description>
        <p>
          Evaluates EXPRESSION as an assertion, an assertion passes if (FUNCALL *CLUNIT-EQUALITY-TEST* VALUE EXPRESSION) returns true.
          FORMS and their values are printed if the test fails.<br/>
          <code>
            (let ((*clunit-equality-test* #'string=))<br/>
            &#160;&#160;&#160;(assert-equality* "some string" "another string")) ; This assertion fails.
          </code>
        </p>
      </description>
    </symbol>

    <symbol name="assert-expands" type="Macro">
      <argument  value-type="t" arg-type="required" name="expansion"/>
      <argument  value-type="t" arg-type="required" name="expression"/>
      <argument  value-type="LIST" arg-type="body" name="forms"/>
      <description>
        <p>
          Evaluates EXPRESSION as an assertion, an assertion passes if (EQUALP EXPANSION (MACROEXPAND-1 EXPRESSION)) returns true.
          FORMS and their values are printed if the test fails.
        </p>
      </description>
    </symbol>

    <symbol name="assert-condition" type="Macro">
      <argument  value-type="CONDITION" arg-type="required" name="condition"/>
      <argument  value-type="t" arg-type="required" name="expression"/>
      <argument  value-type="LIST" arg-type="body" name="forms"/>
      <description>
        <p>
          Evaluates EXPRESSION as an assertion, an assertion passes if EXPRESSION signals CONDITION.
          FORMS and their values are printed if the test fails.
          <code>
            (assert-condition arithmetic-error (/ 1 0)) ; This assertion passes.
          </code>
        </p>
      </description>
    </symbol>

    <symbol name="assert-fail" type="Function">
      <argument  value-type="STRING" arg-type="required" name="format-string"/>
      <argument  value-type="t" arg-type="rest" name="args"/>
      <description>
        <p>
          Calling this function is equivalent to signalling a failed assertion.
          The FORMAT-STRING and ARGS are used to print the failure message as follows:
          <code>(format stream "~?" format-string args)</code>
          If you want to achieve a nice looking output message, use pretty printing directives in the format string e.g. "~:@_" instead of "%".
        </p>
      </description>
    </symbol>

    <symbol name="deftest" type="Macro">
      <argument  value-type="SYMBOL" arg-type="required" name="name"/>
      <argument  value-type="LIST" arg-type="required" name="declarations"/>
      <argument  value-type="t" arg-type="body" name="body"/>
      <description>
        <p>
          Defines a test case called NAME.
          DECLARATIONS declares which test suites this test case is associated with as well as any other test cases that it depends on.<br/>
          The test case body is revaluated on each run, so any redefinition of macros and inline functions will be automatically visible without having to redefine the test.
        </p>
        <p>
          A test case will be queued until all tests cases it depends on have been run.
          If all the test cases pass the queued test is executed otherwise its skipped.
        </p>
        <p>
          The DEFTEST macro has three possible forms:
          <code>
            ;; Define a test case not associated with any test suite and with no dependencies.<br/>
            <b>(deftest name () . body)</b><br/><br/>

            ;; Define a test case which is associated with test suites: <b><i>suite1 ... suiteN.</i></b><br/>
            <b>(deftest name (suite1 suite2 ... suiteN) . body)</b><br/><br/>

            ;; Define a test case associated with test suites: <b><i>suite1 ... suiteN</i></b> and depends on tests: <b><i>test1 ... testN</i></b>.<br/>
            <b>(deftest name ((suite1 suite2 ... suiteN) (test1 test2 ... testN)) . body)</b>
          </code>
        </p>
      </description>
    </symbol>

    <!-- CLUNIT-* Classes -->
    <symbol name="clunit-report" type="CLASS">
      <description>
        <p>CLUNIT-REPORT is the class of the report object returned by the functions <a href="#run-suite">RUN-SUITE</a>, <a href="#run-test">RUN-TEST</a> and <a href="#rerun-failed-tests">RERUN-FAILED-TESTS</a>.</p>
      </description>
    </symbol>

    <symbol name="clunit-test-report" type="CLASS">
      <description>
        <p>A CLUNIT-TEST-REPORT is report is created for each executed test case function, see <a href="#test-reports">TEST-REPORTS</a>.</p>
      </description>
    </symbol>

    <symbol name="test-reports" type="Function">
      <argument  value-type="CLUNIT-REPORT" arg-type="required" name="clunit-report"/>
      <return-type>LIST</return-type>
      <description>
        <p>Returns a list of CLUNIT-TEST-REPORTS, see <a href="#clunit-test-report">CLUNIT-TEST-REPORT</a>.</p>
      </description>
    </symbol>

    <symbol name="test-report-name" type="Function">
      <argument  value-type="CLUNIT-TEST-REPORT" arg-type="required" name="clunit-test-report"/>
      <return-type>SYMBOL</return-type>
      <description>
        <p>A returns the name of the test case function the report was generated for.</p>
      </description>
    </symbol>

    <symbol name="test-report-passed-p" type="Function">
      <argument  value-type="CLUNIT-TEST-REPORT" arg-type="required" name="clunit-test-report"/>
      <return-type>(or t nil)</return-type>
      <description>
        <p>Returns true if all the assertions in the test case function were successful.</p>
      </description>
    </symbol>

    <!-- CLUNIT* Conditions -->

    <symbol name="assertion-condition" type="Condition">
      <description>
        <p>Empty condition raised on an assertion.</p>
      </description>
    </symbol>

    <symbol name="assertion-passed" type="Condition" parent="assertion-condition">
      <description>
        <p>Raised during a passing assertion.</p>
      </description>
    </symbol>

    <symbol name="assertion-error" type="Condition" parent="assertion-condition">
      <field name="message" />
      <description>
        <p>Condition signaled if something happens outside a test case.</p>
      </description>
    </symbol>

    <symbol name="assertion-failed" type="Condition" parent="assertion-condition">
      <field name="expression" />
      <field name="forms" />
      <field name="expected" />
      <field name="returned" />
      <description>
        <p>Condition signaled if an assertion fails.</p>
      </description>
    </symbol>

    <symbol name="assertion-fail-forced" type="Condition" parent="assertion-condition">
      <field name="format-string" />
      <field name="args" />
      <description>
        <p>Condition signaled if an assertion-fail is forced.</p>
      </description>
    </symbol>

    <symbol name="test-suite-failure" type="Condition">
      <field name="test-errors" />
      <field name="test-failed" />
      <field name="total-tests" />
      <description>
        <p>Condition describing the high level overview of the test suite failures.</p>
      </description>
    </symbol>

    <!-- DEF* macros -->
    <symbol name="defsuite" type="Macro">
      <argument  value-type="SYMBOL" arg-type="required" name="name"/>
      <argument  value-type="List" arg-type="required" name="parents"/>
      <description>
        <p>
          Defines a test suite called NAME.
          If PARENTS is non-NIL, the test suite is defined as a sub-suite of each of the test suites in PARENTS.
        </p>
        <code>
          (defsuite arithmetic ())<br/>
          (defsuite arithmetic-+ (arithmetic))
        </code>
      </description>
    </symbol>

    <symbol name="deffixture" type="Macro">
      <argument  value-type="SYMBOL" arg-type="required" name="suite"/>
      <argument  value-type="SYMBOL" arg-type="required" name="(plug)"/>
      <argument  value-type="LIST" arg-type="body" name="body"/>
      <description>
        <p>
          A fixture defines a code template that is wrapped around the code of each test case and test suite that inherits from SUITE.
          The test case body is plugged into the template at the position identified by PLUG.
          Fixtures are expanded at runtime, so the fixture that will wrap around a test depends on the test suite call stack.
        </p>
        <code>
          (deffixture arithmetic (@body)<br/>
          &#160;&#160;(let ((x 0) (y 1) (z 2))<br/>
          &#160;&#160;&#160;&#160;@body))
        </code>
      </description>
    </symbol>

    <symbol name="undeftest" type="Macro">
      <argument  value-type="SYMBOL" arg-type="required" name="name"/>
      <description>
        <p>
          Undefines a previously defined test case.
        </p>
      </description>
    </symbol>

    <symbol name="undefsuite" type="Macro">
      <argument  value-type="SYMBOL" arg-type="required" name="name"/>
      <description>
        <p>
          Undefines a previously defined test suite.
        </p>
      </description>
    </symbol>

    <symbol name="undeffixture" type="Macro">
      <argument  value-type="SYMBOL" arg-type="required" name="name"/>
      <description>
        <p>
          Undefines a previously defined test suite fixture.
        </p>
      </description>
    </symbol>

    <symbol name="run-test" type="Function">
      <argument  value-type="SYMBOL" arg-type="required" name="name"/>
      <argument  value-type="(or t nil)" arg-type="key" name='(report-progress t)'/>
      <argument  value-type="(or t nil)" arg-type="key" name="use-debugger"/>
      <argument  value-type="(or t nil)" arg-type="key" name="stop-on-fail"/>
      <argument  value-type="(or t nil)" arg-type="key" name="(print-results-summary t)"/>
      <description>
        <p>
          Executes a test case called NAME.
          If REPORT-PROGRESS is non-NIL, the test progress is reported.
          If USE-DEBUGGER is non-NIL, the debugger is invoked whenever an assertion fails.
          If STOP-ON-FAIL is non-NIL, the rest of the unit test is cancelled when any assertion fails or an error occurs.
          If PRINT-RESULTS-SUMMARY is non nil the summary results of tests is printed on the standard output.
        </p>
      </description>
    </symbol>

    <symbol name="run-suite" type="Function">
      <argument  value-type="SYMBOL" arg-type="required" name="name"/>
      <argument  value-type="(or t nil)" arg-type="key" name='(report-progress t)'/>
      <argument  value-type="(or t nil)" arg-type="key" name="use-debugger"/>
      <argument  value-type="(or t nil)" arg-type="key" name="stop-on-fail"/>
      <argument  value-type="(or t nil)" arg-type="key" name="signal-condition-on-fail"/>
      <argument  value-type="(or t nil)" arg-type="key" name="(print-results-summary t)"/>
      <description>
        <p>
          Executes a test suite called NAME.
          If REPORT-PROGRESS is non-NIL, the test progress is reported.
          If USE-DEBUGGER is non-NIL, the debugger is invoked whenever an assertion fails.
          If STOP-ON-FAIL is non-NIL, the rest of the unit test is cancelled when any assertion fails or an error occurs.
          If SIGNAL-CONDITION-ON-FAIL is non-NIL, run-suite will signal a TEST-SUITE-FAILURE condition if at least either a test fails or signal an error condition.
          if PRINT-RESULTS-SUMMARY is non nil the summary results of tests is printed on the standard output.
        </p>
      </description>
    </symbol>

    <symbol name="rerun-failed-tests" type="Function">
      <argument  value-type="(or t nil)" arg-type="key" name='(report-progress t)'/>
      <argument  value-type="(or t nil)" arg-type="key" name="use-debugger"/>
      <argument  value-type="(or t nil)" arg-type="key" name="stop-on-fail"/>
      <argument  value-type="(or t nil)" arg-type="key" name='(last-report *last-clunit-report*)'/>
      <argument  value-type="(or t nil)" arg-type="key" name="(print-results-summary t)"/>
      <description>
        <p>
          Reruns all failed tests recorded in LAST-REPORT which defaults to the report of the previous test run.
          If REPORT-PROGRESS is non-NIL, the test progress is reported.
          If USE-DEBUGGER is non-NIL, the debugger is invoked whenever an assertion fails.
          If STOP-ON-FAIL is non-NIL, the rest of the unit test is cancelled when any assertion fails or an error occurs.
          if PRINT-RESULTS-SUMMARY is non nil the summary results of tests is printed on the standard output.
        </p>
      </description>
    </symbol>

    <symbol name="get-defined-tests" type="Function">
      <description>
        <p>
          Returns a list of all defined test case names.
        </p>
      </description>
    </symbol>

    <symbol name="get-defined-suites" type="Function">
      <description>
        <p>
          Returns a list of all defined test suite names.
        </p>
      </description>
    </symbol>

    <symbol name="defined-test-p" type="Function">
      <argument  value-type="SYMBOL" arg-type="required" name="test-name"/>
      <description>
        <p>
          Returns T if a test case called TEST-NAME is defined, otherwise returns NIL.
        </p>
      </description>
    </symbol>

    <symbol name="defined-suite-p" type="Function">
      <argument  value-type="SYMBOL" arg-type="required" name="suite-name"/>
      <description>
        <p>
          Returns T if a test suite called SUITE-NAME is defined, otherwise returns NIL.
        </p>
      </description>
    </symbol>

    <symbol name="get-child-tests" type="Function">
      <argument  value-type="SYMBOL" arg-type="required" name="suite-name"/>
      <description>
        <p>
          Returns a list of all test case names that are children of the suite called SUITE-NAME.
        </p>
      </description>
    </symbol>

    <symbol name="get-child-suites" type="Function">
      <argument  value-type="SYMBOL" arg-type="required" name="suite-name"/>
      <description>
        <p>
          Returns a list of all test suite names that are children of the suite called SUITE-NAME.
        </p>
      </description>
    </symbol>
  </symbols>
</asdf>
